🏃‍♂️ API de Atletas - Documentação Completa

📋 Visão Geral

A API de Atletas é responsável por toda a gestão de atletas no sistema CordenaAi, incluindo cadastro, atualização, consulta, relacionamento com responsáveis e equipes, além de funcionalidades específicas como pesquisa e gerenciamento de mensagens.

🎯 Endpoints Disponíveis

1. GET /api/Atletas

Obter Lista de Atletas

2. POST /api/Atletas

Criar Novo Atleta

3. GET /api/Atletas/responsavel/{identificador}

Obter Atletas por Responsável

4. GET /api/Atletas/{id}

Obter Atleta por ID

5. PUT /api/Atletas/{id}

Atualizar Atleta

6. GET /api/Atletas/pesquisar

Pesquisar Atletas

7. GET /api/Atletas/equipe/{equipeId}

Obter Atletas por Equipe

8. POST /api/Atletas/cadastrar

Cadastrar Atleta (Endpoint Específico)

9. PUT /api/Atletas/atualizar/{alunoId}

Atualizar Atleta por ID de Aluno

10. GET /api/Atletas/mensagens/{id}

Obter Mensagens do Atleta

11. POST /api/Atletas/{id}/inativar

Inativar Atleta

⚡ Operações em Massa

12. POST /api/Atletas/mover-em-massa

Mover Múltiplos Atletas Entre Turmas

13. POST /api/Atletas/remover-em-massa

Remover Múltiplos Atletas de uma Turma

👥 Sistema de Papéis

Conceitos Fundamentais

O sistema utiliza dois tipos distintos de papéis para gerenciar permissões e funções:

1. PapelNaTurma - Papel do Usuário na Turma

Define a identidade/cargo geral que um usuário tem dentro de uma turma específica.

Valor Nome Descrição
1 Aluno Estudante regular da turma
2 Atleta Atleta/estudante esportivo
3 Professor Professor responsável pela turma
4 Monitor Monitor/auxiliar estudante

2. PapelId (HorarioUsuario) - Papel no Horário

Define a função operacional que um usuário tem dentro de um horário específico (aula/treino).

Valor Nome Função
1 Auxiliar Quem auxilia na aula ou treino
2 Professor Quem conduz/ministra a aula ou treino
3 Aluno/Atleta Quem participa/assiste a aula ou treino

Mapeamento entre PapelNaTurma e PapelId

Quando um atleta é vinculado a um horário, o sistema mapeia automaticamente o papel da turma para o papel do horário:

PapelNaTurma (Turma) Valor → PapelId (Horário) Valor Lógica
Aluno 1 → Aluno/Atleta 3 Quem aprende/participa
Atleta 2 → Aluno/Atleta 3 Quem treina/participa
Professor 3 → Professor 2 Quem ensina/conduz
Monitor 4 → Auxiliar 1 Quem auxilia/monitora

📌 Definição do Enum PapelNaTurma

Localização: InMinds.CordenaAi.Api/Modules/Hierarquia/Models.cs

public enum PapelNaTurma
{
    Aluno = 1,
    Atleta = 2,
    Professor = 3,
    Monitor = 4
}

Exemplo Prático

Cenário: Mover João (Atleta) para nova turma com horário

POST /api/Atletas/mover-em-massa
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["joao-id"],
  "turmaAtualId": 5,
  "turmaDestinoId": 9,
  "papelNaTurma": 2,
  "horarioId": 12
}

Resultado:

📊 Cenários de Mapeamento

Cenário 1: papelNaTurma = 1 (Aluno)

{
  "usuarioIds": ["joao-id"],
  "turmaAtualId": 5,
  "turmaDestinoId": 9,
  "papelNaTurma": 1,
  "horarioId": 12
}

Resultado:

Cenário 2: papelNaTurma = 2 (Atleta)

{
  "usuarioIds": ["maria-id"],
  "turmaAtualId": 5,
  "turmaDestinoId": 9,
  "papelNaTurma": 2,
  "horarioId": 12
}

Resultado:

Cenário 3: papelNaTurma = 3 (Professor)

{
  "usuarioIds": ["carlos-id"],
  "turmaAtualId": 5,
  "turmaDestinoId": 9,
  "papelNaTurma": 3,
  "horarioId": 12
}

Resultado:

⚠️ Observações Importantes

🔧 Modelo de Dados

Estrutura do Atleta

{
  "id": "string",
  "nome": "string",
  "dataNascimento": "datetime",
  "cpf": "string",
  "rg": "string",
  "email": "string",
  "telefone": "string",
  "endereco": {
    "logradouro": "string",
    "numero": "string",
    "complemento": "string",
    "bairro": "string",
    "cidade": "string",
    "estado": "string",
    "cep": "string"
  },
  "responsavelId": "string",
  "equipeId": "string",
  "status": "string",
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Cadastro de Atletas

POST /api/Atletas/cadastrar
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "João Silva",
  "dataNascimento": "2010-05-15",
  "cpf": "123.456.789-00",
  "email": "[email protected]",
  "responsavelId": "resp-123"
}

2. Busca de Atletas por Responsável

GET /api/Atletas/responsavel/resp-123
Authorization: Bearer {token}

3. Atualização de Dados

PUT /api/Atletas/atleta-456
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "João Silva Santos",
  "telefone": "(11) 99999-9999"
}

4. Pesquisa Avançada

GET /api/Atletas/pesquisar?nome=João&equipe=equipe-789&status=ativo
Authorization: Bearer {token}

5. Movimentação em Massa

POST /api/Atletas/mover-em-massa
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["atleta-1", "atleta-2", "atleta-3"],
  "turmaAtualId": 5,
  "turmaDestinoId": 9,
  "papelNaTurma": 2,
  "horarioId": 12
}

Casos de uso:

6. Remoção em Massa

POST /api/Atletas/remover-em-massa
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["atleta-1", "atleta-2"],
  "turmaId": 5
}

Casos de uso:

⚠️ Validações e Regras de Negócio

Validações - Operações em Massa

Mover em Massa

Remover em Massa

Validações Obrigatórias - Cadastro

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Cadastro

  1. Validação de dados no backend pela própria API
  2. POST /api/Atletas/cadastrar com dados validados
  3. Associação automática com responsável
  4. Envio de notificação para responsável
  5. Criação de perfil no sistema

Fluxo de Busca e Filtros

  1. GET /api/Atletas/pesquisar com parâmetros
  2. Aplicação de filtros no backend
  3. Retorno paginado dos resultados
  4. Cache dos resultados para próximas buscas

Fluxo de Movimentação em Massa

  1. Validação de permissões: Verificar se usuário é Professor ou Admin
  2. Validação de turmas: Verificar se turmas existem e são diferentes
  3. Início de transação: Garantir atomicidade da operação
  4. Para cada atleta:
  5. Verificar se está na turma atual
  6. Remover horários da turma atual
  7. Persistir exclusão (SaveChanges)
  8. Remover da turma atual
  9. Adicionar na turma destino
  10. Se horarioId informado: mapear papel e adicionar ao horário
  11. Commit da transação: Persistir todas as alterações
  12. Retorno: Detalhamento de sucessos e erros por atleta

Versão: 1.1
Última Atualização: Novembro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi